documentation

[gloddy]

No description provided.

[TakenPilot]

This is resulting from PR #87 .

I think there are a few tasks remaining for documentation as I see them, and "many hands make light work", so let's figure out the remaining tasks and assign them to people. We'll create little PRs for the individual sections, and then it'll be done. : )

So far we have three main pages of documentation, and I think this is how they're kinda working out:

• https://github.com/nymag/byline: This is supposed to be a sales pitch specifically aimed at developers, since we'll later have a github website branch set up for the business sell. All of the documentation here should be less about specifics and more about how we're really good, better than alternatives, and that we built a really good thing. It should also link to our other documentation, and to link to our other related projects.
• https://github.com/nymag/byline/tree/master/lib: This seems to be a narrative explaining the root ideas that everyone involved with using project should understand. Understanding that people's eyes tend to glaze over when they see data structures or math, we're mainly trying to introduce root ideas in a way that isn't scary, but still gets the point across very strongly.
• https://github.com/nymag/byline/tree/master/lib/routes: This seems to be very technical reference material about our routes, since routing is very specific.

So what I'm thinking is that we keep this kind of structure, where the front page is a sale pitch for a specific audience, the second-level of docs are friendly narratives or guides, and then the deep documentation is reference material about how to use the library. We probably don't need to document anything that we don't intend for them to use (i.e., explaining how we generate ids), but we should document how we intend them to use this project, and how they can contribute to the project. Where each bit of information lives is going to be the interesting part.

Tasks

1. I propose that we move detailed discussion of CSS and preprocessors to that project (https://github.com/nymag/responsive-filenames), but still reference that project and how we use it explicitly.
2. I propose that we move detailed explanations of the schema to the editor component (https://github.com/nymag/byline-editor), because it's the one that changes to the schema will affect. Byline just serves the schemas on request, so we should reference the project and explain that as part of our front-page sales pitch.
3. I propose that we consolidate the client.js/server.js/media folder/components/layouts/sites structure discussion to a single section, and that if it gets too large, we should move it to its own page. Anything that's not about the sales-pitch to developers should be second-level. We should reference it and convince them it's really amazing, but reference material is difficult to make into a narrative, and we'll end up just staring at it forever trying to serve two purposes. So let's divide them up?
4. I also propose that we avoid illustrations in the readmes, and so every reference to illustrations be removed. Because the readmes are in markdown, which is designed to be read in and out of a markdown preview, those images will often not be shown. If they're very important for some example or explanation, it will reduce the effectiveness of our documentation. Rather, they should probably live on our website.
5. I propose that we remove all the TKs. We're getting ready for release, and any TK means we're not release ready.

What does everyone think? Are these tasks good? Is this a good plan?

[nelsonpecora]

I agree with these. Per 3, that documentation should be in lib/ (i.e. second-level documentation)

What's the deal with 4? Do we have any images anywhere, or are you just cutting this off at the pass?

[TakenPilot]

Per 3: Yeah, it could be in lib. I've also seen people create more readme's at the root level too, and then they're linked to from the main page. Maybe the lib/ documentation should be moved to another file at root, so we can have multiple second-level pages.

Per 4: Yeah, there are TK's about images in the above PR (#87), and it seems they have their own sections and that those sections rely on those images.

[nelsonpecora]

Ah, roger.

[cruzanmo]

I am on board with the general approach of a top-level sales pitch, second-level narratives/guides, and then deeper technical documentation. Linking well between them seems important.

[gloddy]

I don't necessarily disagree with the above, but I could see some table flipping as we get further in.
The outline in my head is:

• top-level Byline Readme: the pitch + general tour (organisation/compilation/editing) with links to...
• per-module readme.
• Examples folder with instructions in readme.
• Web/Slides: Design/Product/Business pitch: this is more for the slideshow/website highlighting these aspects in the appropriate presentations.

Other notes:

• responsive-filenames readme only covers it's particular implementation. A very short part in the readme will say 1. here's what it does (default compilation) 2. do what you want (common patterns) 3. here's what we do (responsive-filenames link)
• ditto for js. 1.here's what it does (default compilation) 2. do what you want (common patterns) 3. here's what we do (dollar-slice link)

[nelsonpecora]

Hmm. Let's chat about this after the standup?