Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

I've been trying to apply this approach, and it's generaly been a useful way of forming a holistic view of your docs.

The only quadrant that can be a bit challenging is the explanation: some projects are just relatively straightforward and don't require a lot of background knowledge about the whys. In that case, I've found it best to just stick to a couple of lines on the homepage explaining the project's background and the problems it's solving, rather than a separate, rather barren-looking section of your docs.



What I personally do when stuff is straightforward is question how and why it is straightforward to me.

Usually, I realize it is because it's following whatever is my framework's way of doing things, or it is following the usual specs of the tools I use. In this case, I make a conscious effort to dig up a link to a tutorial on a "standard project", and link it there, an example would be:

> This project is following a Classic Java Spring Architecture (-> links to the spring tutorial), with this and this modification...

You have to imagine that people happening upon your documentation might have a totally life experience than you, they may even be a lowly intern, thrown to your project as the sole maintainer of your code, with only school-taught experience.


That's fine. Or a single "Explanation" or "About all this" page. Or just a paragraph on the main page.

The scheme is not a plan that must be fulfilled, it's a guide or map to help you see where you are and where you need to go.

However, don't be ashamed of barren-looking things. They are OK. The reader won't mind.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: