face reality, choose direction, measure distance

ia-guide/ia-cyoa.tw

@@ -452,38 +452,92 @@ To do this, you need to [[State your intent->State your intent]]
 :: State your intent
 ## State your intent
 
-If you wanted to build a house, you wouldn't start laying bricks until you's had a think about what kind of house you want to build.
+If you wanted to build a house, you wouldn't start laying bricks until you'd had a think about what kind of house you want to build.
 How big is it going to be?
 What materials are you going to use?
 What layout and design is it going to have?
 
 By the same token, you need to think about what you intend for your documentation.
 Is it going to be comprehensive and detailed, or simple and sparse?
-Is it going to use simple language, designed for people who have never done this before, or more technical language, for people who know what they're doing and just need the basics?
+Is it going to use simple language, designed for people who have never done this before, or more technical  language, for people who know what they're doing and just need the basics?
 Is it going to start from the very beginning, or are you going to assume that your readers already have some knowledge?
 
-When you've answered some of those questions, you can expand this thinking to how you're going to update and maintain your doucmentation as well.
-How many writers are you likely to have on the project over time, and what skill level are they likely to have?
+When you've considered these things, and determined the kind of documentation you want to make sure your project has, you're just about ready to [[Face reality->Face reality]]
+
+:: Face reality
+
+## Face reality
+By now, you should have a good idea of what your ideal documentation would look like.
+It would be wonderful!
+A shining beacon of docs goodness, hitting all the critical paths for all your readers, and people will talk about it for years to come!
+
+And it's probably about now that reality is going to come and burst your bubble.
+How are you going to update and maintain your documentation?
+
+It's a grim reality that project documentation needs to be maintained.
+Have a think about how many writers your project might be able to access.
+Are you likely to have writers on the project over time?
+What skill  level are they likely to have?
 Is there any content that already exists elsewhere that you can point to, rather than writing yourself?
 Is there any way you can automate any part of the documentation, such as using code comments to generate API documentation?
 
-When you've considered these things, and determined the kind of documentation you want to make sure your project has, and the kind of docs you can maintain over time, you're just about ready to [[Face reality->Face reality]]
+Make sure you're not biting off more than you can chew, and [[Choose a direction->Choose a direction]]
 
+:: Choose a direction
 
-## Face reality
+## Choose a direction
+Now is when you really get to start making decisions.
+We've done a lot of thinking about readers, and the kinds of things they might want to do.
+We've also thought about the kind of content that you already have, and what might be missing.
+We've also faced reality and recognised that you might not be able to create perfect docs, but you can certainly improve what you already have.
 
-Compellingly target resource sucking systems and long-term high-impact synergy. Continually revolutionize cutting-edge paradigms and multidisciplinary action items. Assertively incentivize empowered e-services without standards compliant leadership skills. Competently create sticky human capital rather than accurate scenarios. Credibly leverage other's covalent metrics via multimedia based imperatives.
+So, which docs do you think you're going to need?
 
+TODO: Work out how to make this clickable --LKB 2020-09-14
 
+* API Project overview: An overview of your API
+* API Quickstart: Simplest possible method of implementing your API
+* API Reference: List of references related to your API
+* Discussion: Longer document giving background or context to a topic
+* How-to: Short series of steps for a particular task
+* Tutorial: A training document for a product or topic
+* General reference entry: Specific details about a particular topic
+* Logging reference: Description of log pipelines
 
-## Choose a direction
+Now you get to decide how to move forward.
+That starts with [[Measuring the distance->Measure the distance]]
 
-Dramatically iterate future-proof relationships rather than sticky action items. Holisticly plagiarize maintainable intellectual capital after 24/365 outsourcing. Monotonectally mesh out-of-the-box niches with alternative infomediaries. Holisticly communicate extensible mindshare for ubiquitous imperatives. Credibly embrace interactive sources and multifunctional methods of empowerment.
 
+:: Measure the distance
 
 ## Measure the distance
+Don't let your docs project be like your New Year resolutions, forgotten and lonely by the end of the year.
+The best way to make sure you stick to your docs goals, is to work out how much you can do, and set a deadline for each step in the process.
+
+The templates will help you understand how much work is involved in each of teh docs you want to write.
+Have a read through the information for each template you want to use, and work out how much time you are going to need to work on it.
+
+Then you can split up docs work like this:
+
+* Planning - 20%
+* Drafting - 50%
+* Reviewing and editing - 20%
+* Production - 10%
+
+So, if you want to write a How-To, and you have five months to do it, you can work out how much time to spend on each task like this:
+
+Three months = Around 100 working days, not counting weekends, and allowing for a few holidays.
+You can adjust this however you like, if you're only working on weekends, for example, or if you have other projects to work on as well.
+
+* Planning - 20 days (4 weeks)
+* Drafting - 50 days (10 weeks)
+* Review & edit - 20 days (4 weeks)
+* Production - 10 days (2 weeks)
+
+
+
+
 
-Globally plagiarize intuitive e-services without standards compliant e-markets. Energistically maintain backward-compatible platforms without cross functional scenarios. Collaboratively actualize goal-oriented users and transparent convergence. Enthusiastically restore low-risk high-yield communities whereas intuitive initiatives. Professionally visualize ethical information before next-generation materials.
 
 ## Play with structure