Proposal: Drupal 8 User Manual Summary TheDrupal8UserManualprovidesqualitydocumentationinmultiplelanguages,aimedathelpingNewcomersorLearnerstobecomeSkilledsitebuildersorsiteadministrators.ItisaconciseguidetobuildingandadministeringatypicalDrupalsite.Therefore,itdoesnotcovereverythinginCore,butalsoisnotlimitedtoCoremodulesandreferencescontributedtoolslikeDrush.ThemanualiswritteninAsciiDoc:apopularopensource,GPLlicensed,plaintextwithmarkdownformat.Itcanbedisplayedon*.drupal.orgorwithinaDrupal8site,anditcanbedownloadedinPDFandotherebookformats.Theinitialversioniswrittenandeditedbyasmallgroupofpeople,forwhichfundingisrequired.Ongoingmaintenance(forexample,forfuturereleases)andfurtherdevelopmentaredonebyvolunteersthroughissuesandpatchestoensureareviewprocess.TheDocumentationWorkingGroupprovidesvolunteermaintainersforthetoolchainandreviewers/committersfortheongoingmaintenance.

Main Idea and Requirements Motivation QualitydocumentationinmultiplelanguageshasbeenidentifiedasakeyneedfortheDrupalcommunity.AnotherkeyneedisfordocumentationthatwouldhelpaNewcomerorLearnerpersonamakethetransitiontoSkilled.ThisproposalwouldresultinaconciseDrupal8usermanual,ownedbytheDrupalprojectandlicensedconsistentlywithotherDrupaldocumentation,whichwouldserveasalearningtoolandcouldbetranslatedintoanylanguage.

Requirements - Content TheaudienceissitebuildersandsiteadministratorsattheNewcomerorLearner

levelinthenewPersonasystem.ThemanualprovidestheinformationthesepeoplewouldneedtobecomeSkilledDrupalusers.

ThemanualcoversthetasksthatsitebuildersandsiteadministratorswouldneedtobuildandmanagetypicalDrupalsites:installation,updates,sitebuilding,configuration,andadministration.ThesetaskscanbeintheDrupaluserinterface,ontheirhosting/server(e.g.,settingupCron),andpossiblywithtoolslikeDrush.

Contentselectionisbasedonbuilding/managingtypicalDrupalsites,notlimitedtoDrupalCore,andnotnecessarilycoveringeverymoduleofDrupalCore.

Themanualincludesbackgroundinformationandterminologyasnecessary,soitcanstandalonewithoutreferringtoDrupal.orgpagesorotherreferences.

Themanualisconcise,ratherthanattemptingtobeacomprehensiveguidetoeverythingyoucandowithDrupal.Itdoesnotcoverprogramming,orgenericweb

topicslikeinformationarchitectureandsearchengineoptimization,butconcentratesonhowtodothetasksatypicalDrupalsitebuilderoradministratorwouldneedtodo.

TheproposedoutlinefortheguideisinAppendixA.

Requirements - Functionality and Technical Theproposedmanual:

Hasmultiplewaystonavigateandfindinformation:tableofcontents,relatedtopiclinks,keywordindex,search.

Followsmoderntechnicalwritingbestpracticesforwritingstyleandsplittingthetextintosmall,crossreferencedtopics(splitintoConceptsandTasks).

CanbetranslatedintoalllanguagesDrupalsupports,vialocalize.drupal.orgoratleastbytheexistinglanguagecommunities.

IsexportabletoPDFasacompletebook,andpossiblytootherebookformats.Ideally,itshouldalsobedisplayable(inmultipageHTMLformat)withinaDrupal8siteandona*.drupal.orgsite.

StoresitssourceinaGitrepository(limitedcommitaccessandeditorialcontrol). Iseditableeitherusingaplaintexteditor,withinaDrupal8site,orona*.drupal.org

site.TheeditingmechanismandformatshouldbeeasyfortechwriterswhoarenotnecessarilyPHPprogrammers.

HasstandardDrupalcontentlicensing(CreativeCommons).

Platform/Technology Thereareseveraloptionsforthetechnologythatcouldbeusedtocreatethismanualandsatisfythetechnicalrequirements.TheproposedsolutionistowritethemanualusingAsciiDoc(http://www.methods.co.nz/asciidoc/index.html),whichisanopensource,GPLlicensed,plaintextwithmarkdownformatthatiseasytoeditandlearn,andisusedbymajorplayersinthecommercialtechnicaldocumentationindustry,suchasOReilly.OncethesourceiswritteninAsciiDoc,itcanbeprocessedtovariousoutputformats,suchasPDF,HTML,andmanyereaderformats.ItcanalsobedisplayedinaDrupalsite,usingtheAsciiDocinDrupalmodule(whichiscurrentlyasandboxprojectforDrupal7:https://www.drupal.org/sandbox/jhodgdon/2265553).PDFandebookdocumentreadersgenerallyhavesearchcapabilities,andAsciidocincludescapabilitiesforautomaticallygeneratinganindexandtableofcontents(fromnotationsinthesource),andcrossreferencesbetweensections.EditingcanbedoneusinganyplaintexteditortheAsciiDocinDrupalmodulealsohasavisualeditorthatcanbeusedfromaDrupalsite,withpreviewcapability.Thesourceforthemanualitselfwouldbemaintainedinadrupal.orgprojectgitrepository.TheAsciiDocinDrupalmodulewouldalsoneedtobepromotedtoFullprojectstatusandportedtoDrupal8.Themoduleisfairlysimple(AsciiDoctoolsdomostofthework),sothiswillnotbedifficult.Somesimplescriptsmayalsoneedtobedevelopedtoprocessthesource

intothevariousoutputformatsinstructionsandsamplescriptsalreadyexistintheAsciiDocinDrupalmodule.

Getting it Done Initial English Version WearerequestingfundingfromtheDrupalAssociationfortwoormorewritersandeditorstoproducetheEnglishversionoftheDrupal8.0manual.Giventhatmuchofwhatwewouldneedtocoverisalreadydocumentedonpagesunderdrupal.org/documentation,thisjobwouldbepartlytakingexistingmaterialandorganizingitintoawellwrittenandconsistentmanual,andpartlywritingnewdocumentationifthatwouldrequirelessworkforaparticulartopic.Foreachsection,onepersonwouldbewriting/compiling,andasecondpersonwouldbeediting.

Budget Ourestimatedbudgetis100hoursforwriting/compiling/indexing,40hoursforcopyandtechnicalediting,and10hoursforanoviceusertotestit,basedonanapproximately50pagePDFbookwithanindex,andwithscreenshotsincludedwhereappropriate.Theplanwouldbetodothenoviceusertestingwithvolunteersatasprint,forinstanceataDrupalCon.

Translations ThelanguagecommunitiesforDrupalwouldbeexpectedtoeithertranslatethemanualviavolunteerlabor,astheynowdoforDrupalCoreandContributedmodulesandthemes,orrequestfundingfromtheDrupalAssociationtotranslateit.

Ongoing Maintenance SincethemanualwillbeastandardDrupal.orgproject,volunteerswillbeabletofileissuesandmakepatches,forsmallerupdates(likefixingbugs,typos,etc.).Theycouldalsocontributenewsections,sothatthemanualcanexpandovertime,althoughthiswillneedtobemanagedcarefully.TheMaintainerswillreview/commitpatchesonavolunteerbasis,justlikeotherContribmodules.TheDocumentationWorkingGroupwillprovidevolunteermaintainersforthetoolchain,includingtheAsciiDocinDrupalmoduleandanynecessaryscripts.Forlargerupdates,likeforthe8.1.xor9.xversionsofDrupal,wewouldprobablyneedtoseekfundingagain,dependingonhowmuchofthemanualneedsattentionandupdates(i.e.,dependingonhowdifferenttheinstallationprocessandadministrativeuserinterfaceisbetweenversions).

Appendix A: Proposed Outline Theexactorganizationandcontentoftheguideissubjecttochange,buthereisthecurrentproposedoutline:

UnderstandingDrupal(terminology,backgroundofCMS)

Installationandbasicsitesettings ModulesandThemes(finding,downloading,installing,uninstalling) Updating:minorversionsofDrupalCoreandmodules/themes Creatingandeditingnodecontent,includingpathaliasesandPathauto Navigation:menus,sitehomepage Blocklayoutandcustomblocks Contenttypesandfields,includingtaxonomy Imagestyles Views Contactforms NonEnglishsitesandmultilingualsites

Appendix B: Previous Similar Proposals Theideaofausermanualorcurateddocumentationhasbeendiscussedseveraltimesinthepast,withnomanualbeingcreated:

Theideaofcurateddocumentationhasbeenpreviouslydiscussedonissuehttps://www.drupal.org/node/1291058.Most/allofthemainideasfromthatissuehavebeenincorporatedintothisproposalsrequirements.

Therewasaplanforhowtomakeasystemforcurateddocumentationathttps://www.drupal.org/node/1095012andrelatedissues.Themainrequirementshavebeenincorporatedintothisproposalsrequirements.

TherewasalsoaplantoputtheDeveloperdocsintotheDrupalCorerepositoryusingAsciidoconhttps://www.drupal.org/node/2106873.Mostoftherequirementsanddiscussionfromthatproposalhavebeenincorporatedhere(asidefromtheideasspecifictothecontent,whichwasprogrammerdocs,notausermanual).

TheConfigurableHelpModule,https://www.drupal.org/sandbox/jhodgdon/2369943,whichiscurrentlyaDrupal8sandbox,allowsamoduletodefineoneormorehelptopicsasconfiguration.Thesetopicsareimportedwhenthemoduleisenabled,andthencanbemanaged,edited,andviewedwithinaDrupalsite.Topicsmarkedastoplevelarelistedontheadmin/helppage,andtopicscanbecrossreferenced.Thismodulecouldbeusedtobuildamanualsatisfyingsomeoftherequirements,butitwouldbemissingatableofcontents,keywordindex,search,andPDFexport.

Appendix C: Survey of Existing Documentation ThereareseveralplacesthatDrupaluserscangonowtofinddocumentationonhowtouseDrupal.Eachhasitsstrengthsandweaknesses,fromtheperspectiveofbeingamanualthatwouldhelpaDrupalNewcomerorLearnerbecomeaSkilledDrupaluser.

Community Documentation section on Drupal.org TheCommunityDocumentationsectiononDrupal.orgisfairlycomprehensive,andcoverssitebuilding,administration,theming,andprogramming.

Ithasdeficiencies: Itisunmanaged,andthereforeofvaryingquality Itishuge,soitsdifficulttonavigateand/orsearch(besidesnotbeingparticularlyor

systematicallyorganized) ItisonlyinEnglish,andthesizemakestranslationvirtuallyimpossibletocontemplate.

Thereisnodesignationofwhichpagesareparticularlyimportanttotranslate. Itisnotsuitabletouseasatutorial,becausenewcomerswouldnothaveanyideaof

wheretostartorhowtoproceed,andthesheervolumeisoverwhelming.Itisnotreallyfeasibletoovercomethesedeficiencieswhilemaintainingthecommunityandanyonecancontributefeelingofthisdocumentationtheseaspectsarewhatmakeitasgoodasitis(forinstance,itseasyforthemaintainerofamoduleoranenthuseduserofittoaddapage/sectionabouttheirmodule,anditseasyforsomeonewhonoticesalackorerrortofixit).

In-Drupal Help Thereissomehelp/documentationavailabletositebuildersandadministratorsavailablewithinaDrupalsite:

TheTourmoduleandseveralDrupalCoretoursgiveyouinpagehelpwithsomeUIpages.

TheHelpblockgivesyoutopofpageinformationaboutunfamiliarconceptsonsomeUIpages.

Themodulereferences(hook_help()foreachmodule)giveyouinformationaboutwhatthemoduledoes,andtheHelppage(admin/help)givesyouanindextothesepages.

The(fornowcontrib)ConfigurableHelpmoduleallowsmodulesandthemestoprovideadditionaltopicsbeyondtheironereferencepage(ifitgetswidelyadopted).

Allofthisinformationistranslated/translatableonlocalize.drupal.org.Deficiencies:

Thereferencesareorganizedbymodule,notbytopic/workflow,andthereisonlyonehook_help()topicpermodule(notmultipletopics,andnoneforthemesorinstallprofiles).

Thereisnologicalorderoroutlinepresented,soyoucantreallyuseitasalearningtool.

Writerscannotwritethiseasily.YouhavetomakeapatchinPHPcode,anditsmessy.

Asofthiswriting,thereisnotacohesivestrategyforwhichtoursareneededinDrupalCore.

Programmer/Themer references on *.drupal.org api.drupal.orgisacomprehensiveAPIreferenceforprogrammersandthemers,supplementedbyadditionaldocumentationonDrupal.orginthemoduleandthemedeveloper

sections.EspeciallyforDrupal8,thisinformationisinprettygoodshape.SoprogrammersandthemerswhocanreadEnglishhaveadequatedocumentationforDrupal8.Forthatreason,thisproposalspecificallyisaimedatsitebuildersandadministrators,notprogrammersandthemers.

Forums, blogs, etc. ManypeoplechoosetowritedocumentationforDrupalontheirownblogsratherthancontributingittotheDrupal.orgcommunitydocumentation.Also,thereareDrupalforums(onDrupal.org,groups.drupal.org,andotherlanguageDrupalsites),aswellasDrupalAnswersonStackExchange,wherepeoplecanaskquestionsandgetanswers.Thisinformationisnotorganizedcentrally,andisnotgenerallyusefulforlearningDrupal(notintutorialformat),butcangenerallybefoundwithanappropriatewebsearch.

Commercially-available books, training, and videos Peoplethatarewillingtomakethecommitmenttowritecomprehensive,indepthdocumentationwouldusuallywriteabook,designtrainingcurriculum,orcreateavideoseriesratherthancontributetothecommunitydocumentation(theymaintaincontroloveritsevolution,getsomerevenue,etc.).So,therearealwaysgoodbooks,videos,andpaidtrainingavailableaboutallaspectsofDrupal(sitebuilding,security,programming,theming,etc.).Booksarerelativelyeasytolocate.ForbooksinEnglish,drupal.org/bookshasalistingservice,andpresumablyotherlanguagecommunityDrupalsitescouldhavesimilarpagesforbooksintheirlanguages.Youcanalsosearchamazon.comorsomeothercomprehensivebookstore.VideosandtrainingcoursesarealsosomewhatfindableonDrupal.org.Deficiencies:

ThevastmajorityofthebooksandvideosareinEnglish,andbecausetheyarecopyrighted,theycannotbetranslatedbywillingvolunteersintootherlanguages.

Thebooksandthehighqualityvideoseriesarenotfree.Thecostcouldbeabarrierforsomepeopleindevelopingcountries.

Highqualitytrainingisdefinitelynotfree,andmaynotbeavailableinanyparticulargeographicalareaorlanguage.

ThebooksarenotintegratedintoyourDrupalsiteorDrupal.org.

Drupal Ladder and similar projects DrupalLadder(drupalladder.org)isaprojectwhoseoriginalaimwastocreateasetoflessonsforpeoplewantingtocontributetotheDrupalproject,primarilyprogramming/patchcontributions.Thesitealsohasotherladders(andalotofspam!)aimedatlearningotheraspectsofDrupal,buttheyarenotverywelldeveloped.ThesiteisonlyinEnglish.

Therehavebeenotherattemptstomakecentralizedareasforcontributingtutorials,videos,etc.,suchasDrupalDojo(whichseemstobedefunct),etc.Noneofthemhasreallytakenhold.

Appendix D: User Documentation in Other Projects WordPress ThemainuserdocumentationfortheWordPressCMSistheCodex(https://codex.wordpress.org),whichisaMediaWikipowered,communitywrittensitesimilartotheCommunityDocumentationintheDrupalproject(withsimilarstrengthsandweaknesses).Theyalsohaveaseparatedevelopercenteredwikisiteathttps://developer.wordpress.org/andanAPIreferenceathttps://developer.wordpress.org/reference(generatedfromincodecomments).TheofficialWordPressdocumentationteam(https://make.wordpress.org/docssomeofwhomarepaidstaffofAutomatticandsomeofwhomarevolunteers)isalsoworkingoncreatingasetofcuratedHandbooks,whichcurrentlycoverContributingtotheprojectandafewdevelopmenttopics.TheyalsoworkonimprovingtheCodex,theinWordPresshelppages,theincodecomments,andthedeveloperdocumentation.Wordpress.com(hostedversionofWordPress)hasamanualathttps://learn.wordpress.com/,whichcoversmostaspectsofhowtosetupablog.Thisispresumablywrittenbystaff.

MediaWiki TheMediaWikiprojectswebsitehashttp://www.mediawiki.org/wiki/Help:Contents(forendusers,coveringeditingtasks)andhttp://www.mediawiki.org/wiki/Manual:Contents(coveringinstallation,administration,andupgrades).Theseguidesarefairlyconciseandorganized,eventhoughtheyarewrittenbythecommunityandeditedinawiki.

phpBB ThephbBBprojectprovidesauserguideavailableinHTMLorPDFathttps://www.phpbb.com/support/docs/en/.Thisiswrittenbystaff,andcoversinstallationandconfiguration.Theyalsohaveaknowledgebasethatiscommunitycontributed,butcuratedandaddedtobystaff.PloneThePloneprojectdocumentationlocatedathttp://docs.plone.org/isagoodexampleofcurateddocumentation.DjangoTheDjangodocumentationcontainsastepbystepguidetobuildingaDjangoapplication.Thecuratedguideiseasytofollowandhelpstoleadnewcomersthroughthenecessaryinformationinanorderthatmakessense.Thetutorialsbenefitgreatlyfromthecohesive

exampleapplicationandonesabilitytoeasilyrelatecurrentstepstopreviouslyexplainedconcepts.https://docs.djangoproject.com/en/1.8/intro/tutorial01/.SymfonyTheSymfonydocumentationissplitintotwosections.TheBook,andTheCookbook.BotharehighlycuratedandemployrigideditorialoversighteditingisdoneviapatchesandGit.TheBook,whilebeingmorecodefocusedthantheproposedDrupal8userguides,providesanexampleofwellwrittenandstructureddocumentationthateasesthetransitionfromnewcomertoskilledSymfonydeveloper.Italsoillustratestheusecaseforversionspecificdocumentation,andtranslationintobothFrenchandItalian.http://symfony.com/doc/2.7/book/index.html