Có người hỏi? Cần bao nhiêu tài liệu đề học Drupal?

Question: Who should be asking "How much documentation is enough?"

Answer: Everybody. Developers, Themers, Managers, CEO’s. Everyone in Software Development.

Code Is Documentation

Code is documentation? Slow down, speedy! However, documentation is simply a collection of documents, and a document is a written or drawn representation of thoughts. That is exactly what code is: a written representation of thoughts that we plan on CPU’s, and most importantly, other programmers, reading. That means the reverse can be true too: documentation is code.

The big concept here is that documentation and code should both follow the same principles. They need to be easy to read and execute. The best project is a self-documenting project, which means one where naming conventions and organization make sense. Just like a well executed essay with five paragraphs (intro, 3 points, conclusion), each piece of a project should start with a strong intro (its organization), proceed with clear main points, and have a conclusion that punctuates the points being made.

...documentation and code should both follow the same principles. They need to be easy to read and execute.

“Self documenting code” is a catchphrase people use to describe code that is so well written that it hardly needs any extra documentation. This code follows standards and reads like English. Code documentation needs to be the same way: if your code includes comments that integrate into an IDE (like API docs), then, surprise! You’re actually writing code. And just like any good code, you need to test it to make sure it works.

I recommend the “newbie test” once you have a project up and running. This just means onboarding someone without any handholding and making sure they have everything they need to get started, so when the project adds more members or gets handed off, there will be less questions and more work done.

The Myths

There are two important myths that are constantly perpetuated in Software Development-land. The first one is the “Smart Person Mythology”. This is the idea that you shouldn’t have to hand-hold competent people and they can onboard themselves because they’re smart and can figure it out. The problem is that smart people don’t want to waste time proving they’re smart: they’d rather solve the problem and move on with putting their time to better use. Any instance where you can effectually reduce future time wasted just by putting a few notes in a centralized location is time well spent.

The second myth is the “Job Security Mythology”. This is the idea that if your code is clever enough, you’ll always be needed to update and write more clever code, and you’ll always have a job. This excuse is mostly propagated by people too lazy to seek new challenges. The best code is written for the audience of other programmers and most good programmers want to move on with new challenges rather than being stuck in a comfortable loop.

...smart people don’t want to waste time proving they’re smart...

There’s a story about two programmers. The first programmer found what he was doing repetitive, so he automated it. He got fired a week later after redditing all the time and was replaced with his own program, and so went online and complained to everyone that he got fired for doing his job. The second programmer found what he was doing repetitive, so he automated it. He then went to the CEO and started going around the company automating as many things as possible. His manager still tried to fire him, but the CEO reversed the decision and fired the manager as the programmer was actually doing his job. The moral of the story? Write good code and documentation, and keep writing if you’re worried about job security.

Less SOP's, more EXE's

Explanations are A WASTE OF TIME!

Isn’t that contradictory to an article emphasizing the importance of documentation? Absolutely not. You should approach writing your documentation with the mindset that if your target audience can’t find it useful and start working through it immediately, you’re wasting time explaining things. This often means:

• Separating training from documentation. Train for things that should be known across most projects, and Document the things that aren’t.

• Be agile! Don’t spend time on documentation if it could be a process instead.

• Turn Documentation into Processes, Processes into code!

I’m coining a phrase here: Less SOP’s, more EXE’s - which means, if you can turn something into a Standard Operating Procedure, it’s worth doing a cost-benefit analysis to turn it into code. Also, always be aware of TMD - Too Much Documentation. You want to avoid describing obvious things like syntax or utility functions (such as “// Function start.” or “// Connect to DB.”)

Good code answers the Who, What, When, Where, and How.
Good comments should answer the Why (and not just because Manager X told me so).
If your code starts answering the why, it’s probably time to let the machines take over...

What do I need to document?

Since I get this question a lot, I’ve typed up a convenient list that applies to most software development projects, not just Drupal ones.

• Project Management - This is the code you write to set your programmers in motion. If your Goals, Design Documents, Discovery, and Analysis aren’t clearly and efficiently written, your developers will have just as hard of a time as a computer would with unclear and inefficient code.

• Project Management - It’s so important it’s here twice. Make your goals clear!

• Organization - Naming conventions, file structure. If it’s not covered in training, it needs to be documented.

• Onboarding - Anything that is not covered in training that you need to know to get started on a project. You should always have an onboarding document, even if it’s just 10 bullet points of software install guides, as you never know when you’ll need help on a project from someone who hasn’t built something your way before.

• Code - Walk through what you’ve written. The easier it is to read, the easier it will be to get help or hand it off. Code readability is always the most important! If you need to write something for efficiency’s sake that isn’t quite clear, make sure your comment is the english version of the code. Always run code through the Who, What, When, Where, How, Why questions, and if you can’t answer any of them, add that information in.

• Training - Make your ground rules for what contributors need to know obvious, organized, and easy to reference. This will definitely reduce frustration and miscommunication on a project.

Documentation doesn’t have to be a boring process. Just like everything in life, the more documentation you write, the better you will become. As a general rule, if you spend more than 5 minutes actually writing down the documentation to a single idea (function, docblock), then it’s far too convoluted to be covered clearly and you need to rethink your approach. I reference the above list every time I start a project.

Good luck on improving the documentation workflow in your workplace!