Hacker News new | past | comments | ask | show | jobs | submit login

Sounds good, but I'm stuck with how to apply that to my current documentation. I need a how-to right now and all I get is an explanation.



> I need a how-to right now and all I get is an explanation.

This isn't a reasonable expectation. Your current state of documentation may be very different from some-other-software's current state of documentation. There may (or may not) be commonalities across those states, but assuming the most conservative situation leaves you with no commonality and the author's only option is to write the explanation for you. From there, you have to think about what transformations you need to apply to your current state to get it to the desired state.

Contrast this with game rulebooks. There is a clear commonality: situations where none of the players know any of the rules. Therefore, the rulebook can easily be written assuming no knowledge of the current rules of the game. Players that know the rules of the game can either a) go make everyone coffee and avoid polluting the learning phase with information that stretches the patience of the folks reading the rulebook; or b) claim to the players that don't know the rules that the rulebook is useless and they can do a much better job explaining all the nuances much better than the person that designed the game.


Did you not read the link? The reference should be obvious. I'm giving the link too much credit calling it 'explanation' but it isn't even an example of what it advocates in any case.




Consider applying for YC's Spring batch! Applications are open till Feb 11.

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

Search: