pantsbuild #general

I would much rather worry about content. “You can’t put lipstick on a pig.” I do think we have a lot of good documentation, but I think for someone just getting started or trying to troubleshoot a particular problem its a lot to wade through.

stocky-greece-3497

08/07/2015, 6:24 PM

yep, fair enough- reorganizing is a-ok, but I think plain-text vs. markdown vs. rst seems like a bikeshed

stocky-greece-3497

08/07/2015, 6:25 PM

(tough for me to say coming from the peanut gallery, so definitely do whatever you all want to since I don’t have full context simple smile

bored-art-40741

08/07/2015, 6:26 PM

Our documentation isn't particularly discoverable for new users. Part of that is missing major articles that need to be written, but part of it is also layout and style of the existing site

bored-art-40741

08/07/2015, 6:26 PM

I agree that the markup format is a bikeshed--I think that choice should be entirely governed by what the standard toolchain for this process is. AFAIK that's still Sphinx

stocky-greece-3497

08/07/2015, 6:27 PM

I’ve been able to point people to the python doc pretty easily, but it would be nice if more things were documented, etc

stocky-greece-3497

08/07/2015, 6:27 PM

whether I link to the pantsbuild site or the markdown on github itself isn’t a big deal to me + the engineers I send ‘em to

stocky-greece-3497

08/07/2015, 6:28 PM

(just as a user + evangelist)

stocky-greece-3497

08/07/2015, 6:28 PM

so if I could request to just stick with whatever format already exists then keep kicking butt on more content, that’d be my preference (again, as a user)

stocky-greece-3497

08/07/2015, 6:28 PM

but take that as just one data point, etc etc

rough-minister-58256

08/07/2015, 6:33 PM

I think the bigger problem to solve outside of the content is the look/feel. psychologically, “nicer” sites are associated with “better” work. case in point: https://buckbuild.com/ vs http://pantsbuild.github.io/howto_contribute.html; as a new user, intern, dev etc which project would you think is more mature?

rough-minister-58256

08/07/2015, 6:34 PM

as superficial as it seems, appearances can count for a lot

rough-minister-58256

08/07/2015, 6:35 PM

hence the goal here is to simply get onto a nicer looking site, the format in which we get there by is less important imo and we should learn from our past decisions

bored-art-40741

08/07/2015, 6:35 PM

=kwlzn I do not agree with the extreme position of "content is all that matters"

bored-art-40741

08/07/2015, 6:35 PM

I think appearance very much matters

enough-analyst-54434

08/07/2015, 6:35 PM

I guess I'd love to see advocates of pretty do the work

enough-analyst-54434

08/07/2015, 6:35 PM

As in advocates for anything

enough-analyst-54434

08/07/2015, 6:35 PM

If you mean it - do it

bored-art-40741

08/07/2015, 6:36 PM

My solution for making it pretty is to make it use a standard toolchain, i.e. sphinx. That's sufficiently disruptive that it shouldn't be done without consensus

enough-analyst-54434

08/07/2015, 6:37 PM

I guess I disagree - if you posted an RB that converted the site to rst I don't think anyone would complain

enough-analyst-54434

08/07/2015, 6:37 PM

You did the work

bored-art-40741

08/07/2015, 6:37 PM

Hm. I'm curious what others think about this particular question

astonishing-jelly-60479

08/07/2015, 6:40 PM

are the default or otherwise publicly available sphinx themes enough for pants or would twitter or somebody want to create a brand identity for it?

bored-art-40741

08/07/2015, 6:40 PM

I'm perfectly happy with the default theme

astonishing-jelly-60479

08/07/2015, 6:40 PM

i think the default sphinx stuff would provide a nice free bump in appearance right now that would be themeable later

bored-art-40741

08/07/2015, 6:40 PM

Then changing out a color scheme and logo is far easier and more maintainable than building and maintaining an entire layout and theme