Is documentation good enough for scripters-converting-to-construct?

Post reply
0 favourites
  • 3 posts
From the Asset Store
Good Night, Viral Nighty Night Story Book App Template
$29.99 USD
Setup and ready for your art, animations and story. Viral Storybook App Template.
Boxels's avatar
Boxels

  • EDIT: revised the "NEED" section, in response to Ashley's comment "we have 10k tutorials."

    NEED:

    TL/DR: "Docs are the weakest link in a great product, for at least a few paying users."

    Call me a "scripter learning to code games".

    - I've written a LOT of script code, ie tech art for games.

    - I have weak understanding of event-driven coding design/architecture. I have some idea of basics (core loop, events, etc) but haven't designed and built entire games professionally.

    - I buy licenses and 3rd party solutions (assets, plugins, etc)

    - I love Construct. It is well built and has good support for commercial output.

    - Construct's docs are the main frustration that makes me consider switching to another game engine. I'm spoiled by Autodesk, Unity, and Microsoft C# - ie well written reference docs. Here I find myself stuck often, and finding solutions is really slow (days to weeks). Details below.

    Is it just me? Maybe. I saw at least a few other users posting that seem like me.

    Is there no way to learn this faster? I know lots of senior users post "no avoiding the hard work of grasping coding". Maybe so. But wouldn't it be awesome if Construct was the fastest and best way to grasp it?

    Does Scirra already know there aren't enough users like me to justify effort? I'd like Scirra to have current data from a fair sample of their users, so they know if ...

    1) their most valuable users can be segmented usefully by shared needs,

    2) do docs work for EACH of these segments, so

    3) overall, their existing docs are sufficient or not.

    (maybe they have this already, and know there's no problem! I hope so.. I've seen a few other forum posts. How many folks like me are silently quitting?)

    MORE SPECIFIC NEED:

    Existing tutorials aren't working for me. They make sense by themselves, but hard to apply when I build my own game.

    The FAQ is where I thought I'd find official answers to common stumbling blocks that users like me hit -- 'greatest hits' from the forums, validated by Scirra staff. but it's very, very brief.

    - Search doesn't work for most of my needs. It's easy to search for "fog effect" but hard to name the terms to search for structure and architecture problems.

    - I sometimes find answers in forums or in tutorials, but like all forums, answers are incomplete, unofficial, and sometimes wrong or obsolete.

    - I use the manual a lot because I can find topics, but content is too terse. I wish it linked to more recent or thorough discussion of topic. I especially need examples of typical usages, and FAQ discussion ("I got the basics of Functions, but how does execution flow when multiple sub-functions run? Is why doesn't it...")

    DESIGN CHALLENGE:

    The need above is How can Scirra get us intermediate/advanced user to shoulder the burden of improving documentation? I will propose one solution in reply. Please, everyone on this thread, critique it there and/or propose your own ideas.

    REQUIREMENTS:

    1) measure the docs experience for new/intermediate users. Improve if needed.

    3) docs problems are addressed, with workload on Scirra staff same or less than now.

    Fellow users, answer this challenge, if you are so inspired, in a reply post.

    Tagged:

  • My proposal is named "joshcrowd" and is half-baked and sprawling right now.

    PROCESS:

    1) Understand and Design:

    study users, identify big changes needed.

    2) build system.

    Scirra builds the structural changes and tools needed.

    3) run and maintain.

    Scirra launches and manages the new help system as it builds itself.

    PARTS:

    1) HELP SQUAD: To create good content, Scirra gets intermediate and expert users to spend time improving docs. This section sketches ideas for what might motivate such users.

    2) "Big Fixes": Scirra staff improve structure of help experience. Once big problems are confirmed with the docs experience, they build tools/process to enable HELP SQUAD to do the rest of the work.

    a) make the official manual, the hub of docs.

    b) make it easier and quicker for new/intermed users to access answers

    c) add new ways of getting help

    3) Create a FIX LIST: Work that the HELP SQUAD can do with little/no involvement from Scirra, once the big fixes are done.

    4) NERVES: get constant feedback on docs, and get it to those who can use it.

    ---------------

    HELP SQUAD

    How will Scirra recruit enough intermediate/advanced users to do all this work? Assuming these users don't want to donate their time for free, Scirra needs to strike a deal. What do these users want?

    1a) Scirra announcement: Anyone who we notice improving docs significantly gets...

    [] a "priority" email to Scirra devs

    [] a free copy of Construct

    [] credits in Construct

    [] listed as "recommended consultant" on Scirra resources

    [] to view and vote on priority of upcoming features

    [] to design a Construct feature that takes 10 hours for Scirra staff to implement

    [] exclusives - invitations to studio, conference elite treatment, etc.

    [] paid / income - e.g. a % of Construct sales.

    Just a brainstorm list here. identifying which of these are best is part of the "big fix" work.

    1b) Scirra can measure and display user community progress toward 1a) by repurposing/making community points and badge systems eg in forums

    ---------------------------

    2. BIG FIXES:

    Here, Scirra staff do some 'classic' UX design e.g. interview users to identify nature of big problems and make structural changes as needed.

    EXAMPLE ASSUMPTION: Users want to generally understand Construct's way, and will follow a tutorial to build some random sample game to learn it.

    EXAMPLE REALITY: Users don't want to grok Construct's way. Our journey is: Do a 'getting started' tutorial, then start building our game. Get stuck during building, look at help because we want to solve a specific problem.

    EXAMPLE SOLUTION: Identify top problems that stump beginners and intermediates. Add mini-tutorials for those problems. Improve access to help in editor, while coding (links on error messages? better error messages?)

    EXAMPLE MEASURE: Less forum posts from new/intermediates. Improved retention and usage of Construct after 30 days of download. more published games per user. higher user conversion rates.

    ---------------------

    3. FIX LIST:

    These are the hugely time-consuming tasks that the HELP SQUAD can do. They're mostly ongoing improvements to content not structure of help system.

    a) Discover the naive search terms users are trying in their attempts to find help. Fix them (SEO plus make a glossary) until users are getting to the correct heading in construct manual.

    b) Every sample code is cross-referenced and/or embedded in Construct manual. "for arrays of numbers example, see line 22 of Block-crusher.c3p here. for arrays from JSON, see line 393-444 of ghost-shooter.c3p here"

    c) Every forum post is reviewed and vetted. "WRONG VERSION" (if search originated from Construct 3 help system) or "OUTDATED" (if older than 5 years) or "PROBABLY WRONG" (for known inaccurate advice)

    d) Every good forum post in "how do I..." or other areas not already linked to manual is starred, and connected to the manual-linked forum topic. For example a post in "how do i..." about sequencing but titled "if/elseif" is linked to "Events" manual topic.

    e) Hugely expand the "best practices" section, by reviewing the feedback and reviewing the common queries in forum "how do i" and/or chats, github comments, other places.

    ----------------

    NERVES

    As with all design, we need feedback from docs users. We need 'little' and 'big' feedback.

    For 'little', we improve what works from other help systems: each help section adds a "I still need help". This records a negative experience, and frwards the click by giving aaccess to more help . Exmaples include:

    [] text chat with intermediates online now

    [] "someone will contact you ASAP." - a message sent out on user's behalf to help squad.

    [] AI-based glossary guessing "suggest looking at Arrays and JSON, see here"

    [] Google search "scirra" plus terms.

    end. whew.

  • Try Construct 3

    Develop games in your browser. Powerful, performant & highly capable.

    Try Now Construct 3 users don't see these ads

  • Users can submit tutorials. There are well over 1000 tutorials there.

Post reply
  • 3 posts
Return to board index
Jump to:
Active Users
There are 1 visitors browsing this topic (0 users and 1 guests)