Question

Effective Writing & Quality Documents Answer both of the following questions: Question A Suggest three to five rules for clear, effective writing that are not mentioned in this lesson. Consider what you have noticed in your business and personal experience, or what you learn from an internet search of the topic. Explain your rules using examples. Question B Explain your personal writing process. What has worked for you in your effort to produce quality documents? What is your biggest writing challenge?

Answer 1

In the 1st situation, meet Jean Harlow. nowadays is Harlow’s 1st day on a brand new project. The team includes a well-established codebase, good operating surroundings, and a strong take a look at suite. As Jean Harlow sits down at her table, she’s excited to urge up to hurry with the team. once the morning stand-up meeting she’s pointed to the project’s documentation for installation with a small grimace from her colleague Riley. He mentions that the docs “might be a touch out of date, however, ought to hopefully be enough to urge you going.” Jean Harlow then spends the remainder of the day following the documentation till she gets stuck, at that purpose she is forced to dig through code or raise colleagues for steerage. What may need to take a couple of minutes becomes a day-long exercise in frustration, meddling Harlow’s initial excitement.

In the second situation, meet Harrison. He’s performing on an online app and finds a library that, initially look, looks implausibly helpful for his project. As he makes an attempt to integrate it together with his codebase he discovers that elements of the API appear to be glossed over within the documentation or maybe unregistered. In the end, he walks far from the project in favor of another resolution.

Though these situations are also slightly exaggerated, I’m fairly sure that a lot of folks will relate. These issues weren't primarily caused by low-quality code, however rather by poor documentation.

If helpful documentation is therefore necessary to the success of comes and developer well-being, why don’t all come to have it? the solution, I believe, is that like sensible code, sensible documentation is tough and time-intense to write down.

In my eyes, there square measure eight rules that we are able to follow to provide sensible documentation:

Write documentation that's tantalizing and clear
Write documentation that's comprehensive, description of all aspects of the project
Write documentation that's skimmable
Write documentation that provides samples of a way to use the computer code
Write documentation that has repetition, once helpful
Write documentation that's up-to-date
Write documentation that's straightforward to contribute to
Write documentation that's straightforward to seek out
The most necessary rule of fine documentation is for it to be as tantalizing as doable. this suggests that we should always aim to write down it within the clearest terms doable while not skipping over any steps. we should always avoid creating assumptions regarding what our users could understand. generally, this may appear to be overkill, and that we are also tempted to mention one thing like “every X developer is aware of regarding Y,” however we tend to every bring our own background and set of experiences to a project. tho' this might end in a lot of long-winded documentation, it's ultimately less complicated, as there's less estimation concerned for developers with all levels of expertise.

The documentation ought to aim to be comprehensive. this suggests that every one aspect of the project square measure documented. unregistered options or exceptions will cause frustration and become a time suck as users and alternative developers square measure forced to scan through code to seek out the answers they have. absolutely documenting all options takes away this type of ambiguity.

When we write documentation that's skimmable, we tend to facilitate users' notice of the content they have quickly. creating documentation skimmable will be accomplished by victimization clear headings, bulleted lists, and links. for giant project documentation, a table of contents or clear navigation can facilitate users to skip straight to what they have, instead of scrolling through one long document.

Documentation that options examples permit users to visualize however they could use the code themselves. Aim to produce samples of the foremost common use cases for the project, whereas belongings the excellent documentation detail each risk.

It is utterly acceptable to incorporate some repetition in the documentation, that the Write the Docs project terms “ARID” (accepts (some) repetition in the documentation). Doing therefore acknowledges that users might not scan the complete docs or that some data has relevancy in multiple places within the documentation. whereas sensible code is also DRY, sensible writing aims to be clear, and generally, this suggests continuance ourselves. Write the Docs project calls out the distinction between writing that's ARID, DRY, and WET during this way:

The pursuit of minimizing repetition remains valiant! ARID doesn't mean WET, therefore the word alternative. It means: try and keep things as DRY as doable, however additionally acknowledge that you’ll inevitably like some quantity of “moisture” to provide documentation.

Effective documentation is unbroken up-to-date. this can be amazingly difficult. we tend to could begin our project with the most effective of intentions and nice documentation, however as our computer code evolves and that we square measure quickly iterating, it will be straightforward to fall out of step. If you're operating as a part of the associate degree agile development team, I like to recommend adding documentation to your team’s “definition of done.” For freelance comes, try and treat documentation as a crucial final step.

Documentation that's straightforward to contribute to is additionally straightforward to stay up-to-date. the only thanks to building documentation straightforward to contribute to are to treat it as code, storing it as text in supply management. the location and book Docs Like Code advocates for treating our docs like our code by victimization supply management, automating builds, and applying computer code development tools and techniques to our documentation practices.

Documentation is simply as useful because it is simple to seek out. Keeping associate degree updated README file and linking to a lot of in-depth documentation at the highest of the README once necessary helps to stay discoverability straightforward.

I hope these pointers square measure helpful as you draft your project’s documentation. generally, it's useful to recollect that documentation isn’t only for alternative developers, however typically for our future selves furthermore. after we come to a project once a variety of months, we are going to appreciate the work we tend to place into clear and up-to-date documentation.

These are the following procedures followed while making quality writing.

Topic outline: A title is the most concise summary potential of a subject whereas it still creating sense. If you look at a news web site or newspaper, for example, you'll be able to get fair gumption of what’s occurring within the world simply by reading the headlines as a result of they're titles that, in as few words as potential, summarize the narratives told within the articles that follow.
Conciseness: Aim for a length within the 2- to the 7-word range—something which will be aforesaid repeatedly in one short breath. One-word titles square measure acceptable just for art (e.g., for books, films, songs, albums, etc.), however, most alternative skilled documents use an affordable variety of words to relinquish a way of the subject, albeit efficient to the purpose of getting no words that don’t completely ought to be there. In scientific papers, titles may be quite long and carry many details, tho' you'll be able to expect that their audiences can seldom pronounce the total title.
Capitalization: Capitalize the primary word notwithstanding what, also as all major words (nouns, verbs, adjectives, adverbs, pronouns, etc.) thenceforth.
Don’t capitalize prepositions (e.g., on, to, from, in, out, of), conjunctions (and, but, or, for, nor, so, yet), nor articles (the, a, an) unless they’re the primary word of the post title or subtitle (Darling,
When together with a combined word (i.e., with a compound-modifier hyphen), leave the second word, the one right away following the hyphen, minuscule (see the primary 2 examples within the titles listed at the top of this subsection).
Structure: Use a noun, verb, or adjective phrase instead of an entire sentence.
Main title: If your title comes in 2 elements with a main title and subtitle, the most title establishes the overall context of the subject, maybe with catchy or clever phrasing, and ends with a colon ( : ) with one house when it, however, none before.
Subtitle: The subtitle follows the most title with an additional specific and careful outline of the document topic.
Position: Centre the title at the highest of the page and embrace 1-2 empty lines below it to separate it from the gap text.
Typeface: Use daring fount to assist draw the attention towards the title, also as color if acceptable.

The biggest issue which I face during writing is

Use/Expression of Words

This applies to not only me but also, particularly to non-native English speakers.

A lot of folks struggle with use/expression of words we tend to|and that we} assume we can’t succeed as an author. a number of US area units even shamed as a result of we expect we tend to don’t qualify to be an author.

The solution: Don’t be afraid to speak/write wherever a great deal of qualified individuals area unit. attempt to build your mistakes shortly so individuals will correct you. Also, accompany those that area unit sensible with the English language, and over time you may notice a pattern. Your use of the English language can improve step by step.

You should conjointly pay longer reading and writing. browse quality blogs that concentrate on serving to individuals become higher writers, browse quality books dedicated to writers, and pay longer writing and writing and writing.