Fóruns

Início » Liferay Documentation

Visualização combinada Visão plana Exibição em árvore
Tópicos [ Anterior | Próximo ]
toggle
Hitoshi Ozawa
Should technical documents be fun?
7 de Novembro de 2012 14:14
Resposta

Hitoshi Ozawa

Ranking: Liferay Legend

Mensagens: 7990

Data de entrada: 23 de Março de 2010

Mensagens recentes

I just came across this page and I do get some chuckles out of it, but my colleagues who are too fluent in English often complain that they find it more difficult to comprehend the content (because they take things too seriously and jokes don't cross borders too well). Just wondering how others are feeling about it.

http://www.liferay.com/documentation/liferay-portal/6.1/development/-/ai/lp-6-1-dgen05-creating-liferay-layout-templates-0

The best is just to delete these in my Japanese documentations but my employer don't like me releasing documents I develop in-house, and I'm not going to make another set of documents for public.
Richard Sezov
RE: Should technical documents be fun?
7 de Novembro de 2012 15:10
Resposta

Richard Sezov

LIFERAY STAFF

Ranking: Regular Member

Mensagens: 198

Data de entrada: 7 de Fevereiro de 2007

Mensagens recentes

We have definitely been making efforts to produce documentation that's fun to read and not so dry and business-like. Some examples:

https://www.liferay.com/documentation/liferay-portal/6.1/user-guide/-/ai/managing-pages-in-liferay-port-1 (The Nose-ster Social Network for your nose, which is throughout the WCM chapters)

https://www.liferay.com/documentation/liferay-portal/6.1/user-guide/-/ai/using-audit-trai-1 (Including a short story to illustrate how audit trails work in Liferay. This introduces and concludes the whole section on audits.)

And there are other smaller sections like the one you found scattered around the documentation. We want to make the documents somewhat fun to read (at least, as fun as we can, given the purpose for the documentation). If the documentation is fun to read, then hopefully more people will read it. At the very least, we can reduce some of the drudgery of your day by providing a laugh or two when you least expect it.

That's the idea, anyway. emoticon
Hitoshi Ozawa
RE: Should technical documents be fun?
7 de Novembro de 2012 15:42
Resposta

Hitoshi Ozawa

Ranking: Liferay Legend

Mensagens: 7990

Data de entrada: 23 de Março de 2010

Mensagens recentes

Yes, I know.

I think it's just a culture. Japanese engineers are very dry and take things too seriously and very strict on syntax. I was wondering how users in other countries are and how they are creating their documents.

We've actually converted the documents to a checklist so users will be able to check each step in the process. I know this won't come too well in other cultures - very boring read. :-)