Commits

Herbert Breunung committed 960a1b9

use case prototypes

  • Participants
  • Parent commits 05a9a30
  • Branches sp3

Comments (0)

Files changed (1)

File doc/CompleteProgramming.pod

 =item Honest and brief communication is key.
 =item All code, data and metadata form one project and go into one repository.
 =item They are all equally important.
+=item Any duplication has to be avoided.
 =item Don't plan new feature, document it from users point.
 =item just annotate technical requirements.
 =item these low level functionalities are testet first in a prototype.
 designed internal API equally as a bug as a crashing function. CP is designed
 to deliver that high standard, without packing too much burden on the programmer.
  Firstly: all aspects of a feature are planned at once - so they're in tune with
-each other. And they are also imlepement together - when details are fresh in
-your memory. And since that also includes comments and documentation, you will
+each other. And they are also get imlepemented together - when details are fresh
+in your memory. And since that also includes comments and documentation, you will
 later know what you have done and why, saving a lot of guesswork.
  Secondly: we reduce duplicate work and duplicate data where possible. CP will
-compel you to think about a problem several times, to ensure you unerstood its
+compel you to think about a problem several times, to ensure you understood its
 implications. But every time you will produce a useful part of the project.
 Every vital information goes into one well structured repository (again holistic!).
-Your highten clarity and low duplication also improves the quality of communication,
-that will mainly take place through your common work (repository).
+Your highten clarity and the low duplication also improve the quality of the
+communication, that will mainly take place through your common work (repository).
  And thirdly: as hinted, the development model knows several decoupled, well
 defined stages that correlate with the natural flow of ideas into materialisation.
 Any stage has only one goal that is set according to its possibilities and with
 Take your time and write down answers in a structured and well readable manner,
 because this gets already shipped into the repository as user docs. In a sense -
 development has already started. Of course these docs will be presented to your
-boss as the project proposal. CP minimizes overhead and forces people to find a
-common language and hopefully a common understanding.
+boss as the project proposal - better they are convincing and well formulated.
 
 Please don't overdo your first plan, since most information you will gather along
 the way.  CP means that new information will get stored quickly in the appropriate
-places - not that work targets change every week. CP knows a lot of well defined
-workflows which spares some agreements people call planning. Some planning will
+places - not that work targets change every week. CP knows well defined workflows
+which spare the team from some agreements people call planning. Some planning will
 be replaced by asynchronous interactions with results that are immediately visible
 to all project member. But still there are meetings, a boss and something similar
 as sprints.
 
 After the rough goal is set and before any "real" coding begins - its time for
-the announced metaplanning. Adapt this document, which is part of the programmers
+the announced metaplanning. Outline the abstraction layers of the program and
+plan when to introduce them during developement. This is most critical, because
+changes on these cause the most growth pain. Write some placesholder now into the
+code base for all eyes to see and all devs to remember. The compiler will tell
+you, if it's coherent.  It also helps you to find the right names for important
+details, so later they will be used consistantly in the docs, code and all the rest.
+
+Second part of metaplanning is: Adapt this document, which is part of the programers
 documentation, to the needs of the project. Maybe your team is smaller and several
 roles will be played by one person or maybe your program has no GUI and you have
-to redefine completeness of a feature. Maybe you have to tweak the role of tests -
+to redefine completeness of a feature. Maybe you want to tweak the role of tests -
 by all means these are not the ten commandments.
 And please give us a feedback when your tweaks seem to work well.
 
 
 =head3 Documentation
 
-As you saw, we start always by writing documentation, forwhy its usually better
-to think before doing anything. And putting it down helps you reflect on it.
-Knowing that it will be read by programmer or users should add pressure,
-or let's say serious focus. But please don't overdo it. Just stick to things
-you're sure about and are plannable right now and be sketchy with the rest.
-Then start crafting placeholder code or prototypes that reflect what you just wrote.
+As you saw, CP starts always by writing documentation, forwhy its usually better
+to think before doing anything. Putting it down also helps to reflect on it.
+And knowing that others will rely on it, should motivate you toward precision.
 
-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.
+The first thoughts about anything are too vague to build a good program from.
+Trial and error and even more thinking have to follow, before it gets useful.
+So why not take what you get in the first minutes, put it in a  readable form,
+(which helps you to understand it deeper) and minimize with the result the effort
+to write the docs after you did coding. Practically that is one trick in CP to
+do more and better quality with less work. As your clairvoyance is most probably
+not fully developed, you need to readjust the doc safter implementation.
+Read details about that in chapter L<Main Program> and L<Itersations>.
 
 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",
 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 anyway, especially 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.
+switching to the users perspective - that's what you need to do for writing good
+docs - you also need to develope good software.
 
 The reason why docs are considered in the "agile" field as less important,
 (agile manifesto says: "Working software over comprehensive documentation")
-because they confuse it with overhead. In CP we don't document planned features,
-just note them 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. For managers its also helpful 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.
-Meetings get more productive too, when arguing has a common knowledge base and
-results will become directly part of the product.
+is because they confuse it with overhead. In CP we only document software parts as
+a first step toward their implementation. Planned ones are just noted in a roadmap.
+Meetings get more productive, when there is arguing about now to be made changes
+in the docs that will go online instantly. Managers as well as customers will get
+high level user docs. They are the basis of most communication. That's because the
+struggle for satisfying agreements, a common language and a good product are the
+same thing. Unifying them makes just sense, improves transparency, demands honesty
+and reduces overhead.
 
 User docs, developer docs and comments, as well as the code itslef are means of
 communication between people. They have to cooperate. All these parts should have
 Less friction here is an enormous productivity boost - a further reason,
 why they gotta be written altogether and by the same people.
 
-Nevertheless things not always turn out as planned. So quite often the docs have
-to be adjusted after the implementation of a feature. That oughta be done anyway,
-as first phase docs were just sketchy drafts, stating what you could know then,
-which becomes more after the coding. Small iterations between these states amplify
-an holistic understanding and overall quality. The exact rules how to iterate
-are part of the chapter L<Itersations>.
-
 
 =head3 Prototypes
 
 These are small, quickly written programs that are test beds for very few things.
 Usually do programer enjoy building them, because they demand less restrictions
 than huge programs and allow much more fast changes and creativity.
-This way ideas get stable without harming the "real code" and coder have more fun.
+This way ideas get stable without harming the "real code" and coders have more fun.
 And if a prototype turns out to be a blind alley, it can be deleted without remorse.
 
 Some may now intervene: "Why not just fork an experimental branch, if we using hg,
 
 CP knows two types of prototypes that are living in two seperate branches.
 That's because the main program has to bridge two endpoints which are too different
-to think about and optimize for at once. That are the hardware or the near
+to think about and optimize for at once. Theset are the hardware or the near
 hardware software layer and the user. For the one side we have functional
 prototypes and for the second use case prototypes.
 
 
 =head4 Use Case Prototypes
 
-users view
+Back to the users perspective. Same basic rules apply, except now you may use
+libs from the main project or some altered/simplified derivatives. Without these
+you can't write this kind of prototype quickly, because in this several low level
+functions get bundeled to a feature. Since this will be a program with only that
+feature, you are free to model it to an ideal state, what maybe wouldn't fit into
+the main branch. This enables a realstic decision making process, how to wranch it
+into the whole or maybe how to alter the main thing.
+
 
 =head3 Main Program
 
 BETTER TESTING — WORSE QUALITY?
 Elisabeth Hendrickson
 
+
+
 =head3 Itersations
 
+
+
 =head3 Releases
 
-see more in L<lib/Kephra/Versioning.pod>
 
-parts to do
+See more in L<lib/Kephra/Versioning.pod>
 
-anderson
-cognitive psychologie