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

But then it is all .. vague. I do hope something better than can be done.. hand drawn diagrams can't represent details at different levels of magnitude, like for example why statecharts are very expressive compared to other diagrams is it's ability to have arbitrary levels of nesting, which is not possible with handdrawn or even printed diagrams.

I feel like resorting to simple hand drawn diagrams, is in a way declaring failure on being able to describe complex software requirements and structure/ behavior in a systematic graphical manner.



What works for me is to do things by hand, until all the possible information I might want to share is present. I call it my inventory.

Then work on refining, editing, deleting, modifying.

Separate the creation from the editing/communication.


This x1000


Just make sure your stuff really expresses something and isn’t just pretty as I see quite a bit.


The details will always have to be looked at by the inheritors - it's more important to not say something wrong or contradictory IMO. When I've had to do something like this in the past I circle through it, documenting the high-level ops before details anywhere. Tricky or especially complicated details next, then the operational details for as much as I've time for.

I'm doing this now for a couple of things I've inherited because my predecessors either never documented it or it's been lost to time. High-level flow, tricky and/or problematic bits with operational & recovery info, then the mundane as I have time. That means the mundane or some of the less-tricky tricky bits will be "vague" for a while.




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

Search: