Movatterモバイル変換

chromium /chromium /src /main /. /docs /documentation_best_practices.md

blob: b8c9e954a8e86dcb33018bdd00f341e390bfb747 [file] [log] [blame] [view]

andybons	3322f76	2015-08-24 21:37:09	[diff] [blame]	1	# Documentation Best Practices
				2
Wesley Moy	32a43ba	2019-04-17 02:07:30	[diff] [blame]	3	"Say what you mean, simply and directly."-
				4	[BrianKernighan](http://en.wikipedia.org/wiki/The_Elements_of_Programming_Style)
andybons	3322f76	2015-08-24 21:37:09	[diff] [blame]	5
				6	[TOC]
				7
				8	## Minimum viable documentation
				9
				10	A smallset of freshand accurate docsis better than a large
				11	assembly of"documentation"in various states of disrepair.
				12
				13	Writeshortand useful documents.Cutout everything unnecessary,while also
				14	making a habit of continually massagingand improving every doc to suit your
				15	changing needs.**Docs work bestwhen they are alive but frequently trimmed,
				16	like a bonsai tree**.
				17
				18	## Update docs with code
				19
				20	Change your documentationin the same CLas the code change.This keeps your
				21	docs fresh,andis also a good place to explain to your reviewer what you're
				22	doing.
				23
				24	## Delete dead documentation
				25
				26	Dead docs are bad. They misinform, they slow down, they incite despair in
				27	new community members and laziness in existing ones. They set a precedent
				28	for leaving behind messes in a code base. If your home is clean, most
				29	guests will be clean without being asked.
				30
				31	Just like any big cleaning project, it's easy to be overwhelmed.If your
				32	docs arein bad shape:
				33
				34	*Take it slow, doc healthis a gradual accumulation.
				35	*Firstdelete what you're certain is wrong, ignore what's unclear.
				36	*Get the whole community involved.Devote time to quickly scan every docand
				37	make a simple decision:Keepordelete?
				38	*Default todeleteor leave behindif migrating.Stragglers can always be
				39	recovered.
				40	*Iterate.
				41
				42	## Prefer the good over the perfect
				43
				44	Documentationis an art.Thereisno perfect document, there are only proven
				45	methodsand prudent guidelines.See
Wesley Moy	32a43ba	2019-04-17 02:07:30	[diff] [blame]	46	[Betteris better than perfect](https://github.com/google/styleguide/blob/gh-pages/docguide/philosophy.md#better-is-better-than-perfect).
andybons	3322f76	2015-08-24 21:37:09	[diff] [blame]	47
				48	## Documentation is the story of your code
				49
				50	Writing excellent code doesn't end when your code compiles or even if your
				51	test coverage reaches 100%. It's easy to write something a computer understands,
				52	it's much harder to write something both a human and a computer understand. Your
				53	mission as a Code Health-conscious engineer is to **write for humans first,
				54	computers second.** Documentation is an important part of this skill.
				55
				56	There's a spectrum of engineering documentation that rangesfrom terse comments
				57	to detailed prose:
				58
				59	1.Inline comments:The primary purpose ofinline commentsis to provide
				60	information that the code itself cannot contain, suchas why the codeis
				61	there.
				62
				63	2.Methodandclass comments:
				64
				65	*Method API documentation:The header/Javadoc/ docstring
				66	comments that say what methodsdoand how touse them.This
				67	documentationisthe contract of how your code must behave.The
				68	intended audienceis future programmers who willuseand modify your
				69	code.
				70
				71	Itis often reasonable to say that any behavior documented here should
				72	have a test verifying it.This documentation details what arguments the
				73	method takes, what it returns, any"gotchas"or restrictions,and what
				74	exceptions it canthrowor errors it canreturn.It doesnot usually
				75	explain why code behaves a particular wayunless that's relevant to a
				76	developer's understanding of how touse the method."Why" explanations
				77	areforinline comments.Thinkin practical termswhen writing method
				78	documentation:"This is a hammer. You use it to pound nails."
				79
				80	*Class/Module API documentation:The header/Javadoc/ docstring
				81	commentsfor aclassor a whole file.This documentation gives a brief
				82	overview of what theclass/ file doesand often gives a fewshort
				83	examples of how you mightuse theclass/ file.
				84
				85	Examples are particularly relevantwhen there's several distinct ways to
				86	use the class (some advanced, some simple). Always list the simplest
				87	use case first.
				88
				89	3. README.md: A good README.md orients the new user to the directory and
				90	points to more detailed explanation and user guides:
				91	* What is this directory intended to hold?
				92	* Which files should the developer look at first? Are some files an API?
				93	* Who maintains this directory and where I can learn more?
				94
				95	4. Design docs, PRDs: A good design doc or PRD discusses the proposed
Quinten Yearsley	317532d	2021-10-20 17:10:31	[diff] [blame]	96	implementation at length for the purpose of collecting feedback on that
andybons	3322f76	2015-08-24 21:37:09	[diff] [blame]	97	design. However, once the code is implemented, design docs should serve as
				98	archives of these decisions, not as half-correct docs (they are often
				99	misused). See
foolip	df2a863	2017-02-15 15:03:16	[diff] [blame]	100	[Implementation state](#Implementation-state-determines-document-repository)
andybons	3322f76	2015-08-24 21:37:09	[diff] [blame]	101	below.
				102
				103	## Implementation state determines document repository
				104
				105	If the doc is about implemented code, put it in README.md. If it's
				106	pre-implementation discussion, includingDesign docs,PRDs,and presentations,
				107	keep itin sharedDrive folders.
				108
				109	## Duplication is evil
				110
				111	Donot write your own guide to a common technologyor process.Link to it
				112	instead.If the guide doesn't exist or it's badlyout of date, submit your
qyearsley	c0dc6f4	2016-12-02 22:13:39	[diff] [blame]	113	updates to the appropriate docs/ directoryor create apackage-level
andybons	3322f76	2015-08-24 21:37:09	[diff] [blame]	114	README.md.Take ownershipand don't be shy: Other teams will usually welcome
				115	your contributions.