Herbert Breunung  committed cba2259

reworked documentation chapter

  • Participants
  • Parent commits 5161a19
  • Branches sp3

Comments (0)

Files changed (1)

File doc/CompleteProgramming.pod

 Knowing that it will be read by programmer or users should add pressure,
 or let's say serious focus. But please dont overdue it. Just stick to things
 you're sure about and are plannable right now and be sketchy with the rest.
-Than start crafting placeholder code or prototypes that reflect what you just wrote.
+Then start crafting placeholder code or prototypes that reflect what you just wrote.
+If you think it through - the first thoughts are too vague to build a good program.
+Either you do for a while try and error to find a good structure and the right
+details, or you start with defining what you want to achieve. This way you get
+the docs right away while doing the necessary thinking and you don't have to write
+them later. Even better - programming will become more streamlined too, because
+you don't have to think about where you going and how to implement it at once.
+And as you will see, we will break up that process into several more steps,
+before coding the final product.
-Because we see code, docs and everything else as one entity, pursuing one goal.
-With bad docs the program is much less usable and enjoyable, hence missing,
-outdated or badly written docs are bugs and should be treated as such.
-Many hate writing docs, because its a lot of work when doing it all at once.
-And its even more work when it describes details you already forgot about or 
-were developed by others. But if you see it as part of the codebase and a
-valuable tool for communicating with the back of your head and your coworkers,
-it will become a time saver. And since you always make some kind of plan,
-you have now to write it down only once, only with more conscience (see L<Main Goal>).
-The perceived quality of the program increases hugely.
+Some devs feel writing docs is unproductive, a waste of time or should be done
+by people more talented to do that. Even if good UI design is "self-explanatory",
+missing docs are crippling the usability and not findable features are not
+distinguishable from not existing ones. Thatswhy only documented features, libs
+and API's are quality work. And since you wrote them, you should document them.
+It would take more time to explain it to a none-techie. And switching to the
+users perspective - that is what you need to do for good docs - you also need to
+develope good software.
 The reason why docs are considered in the "agile" field as less important,
-("Working software over comprehensive documentation")
-because they confuse it with overhead. In "complete programming" we mostly give
-our managers highl level docs as written for the user. That means we have almost
-no overhead and the docs have to be so good that even mangers an understand them.
-To managers its also better when they know that you actually 
+(agile manifesto says: "Working software over comprehensive documentation")
+because they confuse it with overhead. In CP we don't document planned features,
+just note the in a roadmap. And managers will get high level user docs.
+That means we have almost no overhead and the docs have to be so good,
+that even mangers an understand them. To managers its also better to
+understand the language of the user and to know what is actually been done.
+Since the boss will get no special report, it gets harder to cheat or fall into
+other traps of miscommunication, that is enabled by duplication of information
+about one thing. Meetings get more productive too when arguing has a common basis.
-types of documentation
+User docs, developer docs and comments, as well as the code itslef are means of
+communication between people. They have to therefore cooperate seamlessly.
+All these parts should have a common language and define key words and phrases
+in the exactly same way. Less friction here is an enormous productivity boost.
+A further reason, why they gotta be written altogether and by the same people.
 put into code
 just seperate starter
-=head3 Code
-=head3 Coding
+=head3 Main Program
 write after code
 and its stable
+have to change them less
+different angle
 its after thought
-different angle
 =head3 Releases