Dev Website - Feedback

[maidsafe]

As you are aware, we have been working on a standalone Dev Website for the community with the aim of launching it by SAFE DevCon on 23rd April.

Time and time again the community forums show developers enjoy being able to:

• Quickly access information that is relevant to their preferred language/platform

• Get questions answered fast (typically these are split by language and whether you are new to the SAFE Network technology)

• See the latest changes/news easily

The existing SAFE Network documentation can be confusing, is out of date in some cases and spread across many platforms. Ongoing development is vital for the SAFE Network, so providing great information in an easy to consume way will support our existing community better, and encourage more development on the Network. A standalone developer website will be an important tool in the armoury of any SAFE developer.

Therefore we propose a dev specific website which will:

1. Consolidate the currently scattered documents (white papers, API documentation, tutorials) and create a one-stop-shop for links, roadmaps, platform information etc

2. Provide clear pathways for new users to bootstrap

3. Provide information relevant to the user’s preferred language/platform

Below, we outline the mock designs for this website. We would love to hear your feedback on content, design, layout, usability, any features which would be important for launch, and features you would like for future iterations.

Please put your feedback in the comments section below by Wednesday 4th April, to enable us to have the website ready for DevCon.

1. Consolidate

Rather than keeping information solely in the Dev Forum, or in GitHub, a standalone website creates a landing page for all things development. Here the ability to guide users through the key aspects of the SAFE Network is possible as well as continuing to provide links to other resources, and of course back to the Dev Forum.

2. Clear pathways

Right from the homepage, we take the opportunity to provide education and guidance for new users, while keeping it relevant for seasoned developers. The use of banners can be introduced on the homepage which could be used to advertise network/API features; talk about new updates or events; highlight apps on the SAFE Network etc.

Scrolling down the home page new users are led through the bootstrapping process with each of the four key aspects explained sequentially: Understand, Develop, Test, Deploy. With the Get Started button taking users to the Discover page.

3. Preferred programming language/platform

To be able to cater to different languages and platforms we propose three distinct pages - App Devs; Core Devs and Platforms. The overall site structure also reflects this approach:

Note: Options to navigate between App Dev and Core Dev pages are always available from the top of each page. Also, at the top right, a ‘chat’ icon is displayed throughout the website, to ensure quick access to the Dev Forum at all times, enabling community conversations to continue and questions asked at any time.

The App Dev page will include descriptions of the various container types and data types, along with language-specific information:

Users can access their relevant platform/programming language preference via the icons at either the top or bottom of the App Dev page:

Each page outlines installation instructions and examples:

The Core Dev page includes links to each GitHub repository for each of the components, links to RFCs and information about licensing and the various defensive patents in place:

The third and final top-level page is the Discover page. The Discover page walks the user through the main components of the SAFE Network such as the Authenticator, Vaults and the network flavours of local, mock and testnets. Should a user want to deep-dive further, they would navigate to either the App Dev or Core Dev page (as required).

Overall, this website has been designed with the developer front and centre, providing easy access to information that is regularly discussed and accessed via the Dev Forum. Although the intention is not to replace the forum, this website will complement it, providing a one-stop-shop approach to better support our developer community.

We look forward to your feedback and further thoughts on changes and website features to add to our roadmap for the future.

[happybeing]

Quick reaction, as an app developer I’m not sure the App Dev page is answering the first questions that I would have. Talking about containers seems an odd place to start.

My first questions would be about what kind of apps are likely to be suited to this platform, and what are the options available for building apps. Also, what functionality does the platform provide, perhaps with a short example description of how each kind of app would use the features and why this would make sense for users (end user benefits).

I guess it’s also a good place to work in why developers should choose this platform, with a link to a more in depth section on the benefits from the perfective of app developers and service providers.

At this point I’m thinking, mmm I wonder if I could do x, so I might want to leap into API docs for a quick scan, or read a tutorial that shows the main different ways to build a simple app (Web, electron, Python etc).

Containers are more an end user concern, so not the first thing I want to enquire about as a dev. Also, the way they have been laid out in the graphic seems more suited to users than devs. For myself I prefer dense information presentation (less pages/open tabs to flip between while assimilating), so text with diagrams, all on one page for a narrative /tutorial which I scroll rather than split over many pages, or tables of APIs etc rather than use a whole a page that shows something that can be conveyed in a couple of sentences (“By convention SAFE Network organises the user’s files into a set of default root containers, or folders, for files of different type. These are…”).

Hope that helps.

[rob]

I think that another section could be made that gives context suitable for the developer and non-developer alike.

There will be a number of people wanting to know/learn about the SAFE code, but do not want to develop code will be larger than the people who want to become core/app developers. They want to evaluate or see the genius of the system, learn about the core aspects, etc. Yes I know the site is aimed at future/current developers, but it will also be the place people come to to find out what makes SAFE work

This would be a mix of safe primer with more technical papers etc.

I suspect that it could incorporate @happybeing’s suggestion as well. Kinda of a learn about SAFE’s core code and systems. And the language/descriptiveness needs to be aimed at a different level to devoted developer, more for the technical capable but not necessarily coder.

@happybeing

My first questions would be about what kind of apps are likely to be suited to this platform, and what are the options available for building apps. Also, what functionality does the platform provide, perhaps with a short example description of how each kind of app would use the features and why this would make sense for users (end user benefits).

I guess it’s also a good place to work in why developers should choose this platform, with a link to a more in depth section on the benefits from the perfective of app developers and service providers.

[Nadia]

Great feedback @happybeing - first reactions are the important ones, and looking at this from a users point of view, is exactly what we’re after. Thank you very much

[Nadia]

@rob

Yes I know the site is aimed at future/current developers, but it will also be the place people come to to find out what makes SAFE work

Thanks for taking the time to comment @rob and really good point about ensuring we cater for dev’s and non-dev’s alike. This is certainly something we need to look at, because, although we have proposed bootstrapping process from the homepage, this isn’t necessarily the kind of information a non-dev needs.

As you know the maidsafe.net website is being refreshed. Do you think we should provide more non-dev content in there, with links connecting the two websites, or do you think more needs to be included in this dev website independently?

[JPL]

This is a great idea and long overdue and done right it should answer the wishes of the respondents to my survey last year which identified the need for a one-stop-shop for devs. I like the design, it’s nice and clean. I hope someone will be tasked with keeping it updated on a weekly basis to avoid the problem of out of out-of-date info hanging around and also to let interested devs know that it’s an active community. This is really important.

I would agree with @happybeing and @rob that it goes in too deep too soon. An overview of the specific features of SAFE and how these features lend themselves to certain sorts of apps would be the best place to start, including the advantages of SAFE over existing or competing architectures and how devs can exploit them. A broad summary with links to more in depth stuff could maybe go on the homepage as it will be universally applicable.

I would also like to see some step-through worked examples in each of the language areas. I’m not a dev myself but that would be the way I’d want to learn, rather than having to trawl through endless documentation. Blockstack do a good job here IMO. https://blockstack.org/tutorials

Perhaps there could be some exercises, graduating from easy to hard, for those who want to learn the ropes but not necessarily develop an app straight away. So ‘easy’ could be ‘how to write an authentication script’ whereas ‘hard’ could be ‘how to create a messaging app’ or something, with examples in the main supported languages.

It would be interesting to know the points where people tend to get stuck when they try to create apps for SAFE and focus on those, perhaps with some YouTube videos to help them get over the main hurdles.

The link to the Dev forum is good, but it’s not particularly active. Perhaps have some sort of live messaging available too, perhaps with a live feed to keep the homepage dynamic?

[rob]

@Nadia

Do you think we should provide more non-dev content in there

Definitely as much as *you* can

@Nadia

with links connecting the two websites, or do you think more needs to be included in this dev website independently?

The information should reside in the one location since duplication requires people to remember to update both

So accessed from both sites, but the site visitor remains on the site they entered. For instance if I go into maidsafe.net then I can navigate to the so called non-dev pages but remain in maidsafe.net site. And if navigate to the pages from the dev site then I remain in the dev site.

This means the pages have one source but appear as if they are hosted on both sites.

When referring to non-dev pages I also mean that the information will be from overviews to in depth stuff. If I didn’t know SAFE and visited maidsafe.net and navigated to the overview/technical details then I’d like to be able to explore the real technical details of each module too. But also visitors to the dev site might want the same thing.

You must remember that google sends people to whatever depending on their previous searches.

Of course if too hard to do the same info on dual sites then link the visitor to the dev-site and only host the info there. Obviously provide navigation back to maidsafe.net on each page.

[happybeing]

@rob

@Nadia: Do you think we should provide more non-dev content in there

@Rob: Definitely as much as you can

I disagree with @rob here. I think focusing on devs is important, which is at the root of my first reply which is pointing towards well organised, succinct, detailed, easily accessed, more dense information designed to answer the particular questions of developers with as little distraction or messing about as possible. Less is more really.

Just the facts man

The maidsafe.net might be a better place to host articles which are in depth, but which answer non dev technical queries.

[JPL]

I agree it should be dev focused. There can be a funnel though, so you start with the broad issues I allude to above

@JPL

An overview of the specific features of SAFE and how these features lend themselves to certain sorts of apps would be the best place to start, including the advantages of SAFE over existing or competing architectures and how devs can exploit them.

and then narrow the beam, but keeping it clean, simple focused and up to date is key.

[Sascha]

@maidsafe

Provide information relevant to the user’s preferred language/platform

I’m not sure what this means exactly. But please don’t forget about multi-lingual users who care more about the content than about in what natural language it is expressed. I love websites where I can switch natural language easily and end up on a localized version of the same particular page, instead of being directed back to home/root. Just my 2 cents.

[JPL]

It’s referring to programming languages rather than spoken languages.

[Joseph_Meagher]

Feel free to use any content from the SAFE API Overview. I would also suggest adding in a section where developers can add in explanations for how their own applications and websites work.

The development for SAFE API Overview was moved to gitbook (I wasn’t done moving it fully yet which is why it wasn’t announced on the forum) as I was hoping this change would make it easier for people to leave comments, developers to add explanations of their websites and have the content reviewed.

[riddim]

hmhmmm - maybe a blog where people can share their neweset developments …?

not entirely sure if that is beneficial … but a bit like ‘stories’ from safe-devs … then someone who developed a short script to showcase something can publish it there easily to see by anybody and maybe inspire to use that for doing something else (at the same time it would be a bit of a platform for new apps to get known to people … topics in the forum don’t include pictures and the name needs to be appealing to people for digging into it… and then again topics are there to discuss stuff … not just to show something … so there is a difference …) (can such a blog be a rss-stream? not sure how many people actually use those …but the ones doing would probably like it)

just thought i’d mention it (because i was thinking where i would ‘release’ a first version of the python library with some example-notebooks where people can e.g. log into their account and get info about available put-balance / store or retrieve data / maybe a very simple chat stealing mechanisms from the signalling demo … (that’d be my longer-term plan on how to go forward … no planned crappyapps by me but just writing examples on how some features can be utilized/implemented in python … [once i finally managed to get the python api running of course xD …but even neural network stuff can be shown very nicely with notebooks so i guess it could be an easy to digest introduction to safe for pythonistas … anyway … i digress … sorry…] )

@Joseph_Meagher

I would also suggest adding in a section were developers can add in explanations for how their own applications and websites work.

aaaah sorry @Joseph_Meagher … i just dropped my thoughts before reding and just recognized you were pretty much suggesting the same thing

[Shankar_S]

@Sascha

But please don’t forget about multi-lingual users

Yes, we have plans to integrate internationalization within the dev-website.

[oetyng]

I think this is a fantastic idea @riddim.

There will be many app developers who wants to contribute with both the code, work process and various things from the path, as well as the final product. The format of a blog for demonstrating progress of parts, details and features, lends itself better than the forum topics.

So this could give a deep well of examples of all kinds. Additionally, various blog posts could be put together in curated lists linked on front page, or referenced in other blog posts to keep building on each other’s work.

This would make much of content based on community as well. I think that would liven it up, and balance it nicely.
(Maybe it rather belongs somewhere like the SafeAcademy though? Or someplace else.)

And I agree with @JPL and @happybeing about the documentation scope, and what good entry points are.
IMO: First show me what types of apps can be done, then show me examples from these.
This triggers my curiosity and makes my creativity spin with ideas as I look into it. Then when I want to start working, I want to look at detailed documentation, which absolutely can be composed as is shown, with a lightweight overview of components, and ability to dig further into each.

This dev site is such a great initiative.

[cooperka]

My reaction to the title was “YES!” A good dev site would make app development so much more enjoyable.

However, echoing some of @happybeing’s concerns, my reaction to the details and screenshots was “But where is the information?” Most of this is already easily accessible on the GitHub READMEs; it’s not what I’m looking for.

Here are some developer websites as examples of what I’ve found useful:

• MaidSafe’s SAFE API Playground. Amazing.
  • Could it be hosted so new users don’t need to build it themselves?
• The Redux dev site. Straightforward overview, tutorials, examples, and API docs.
  • Could we use GitBook like this to replace docs.maidsafe.net?
• The Apollo dev site. Apollo is an extensive, multi-faceted system with docs for numerous platforms.
  • Something like this would be awesome if we go with a fully custom website – but note that even this is rendered based on GitHub markdown files. The ability for users to submit changes to the dev website is critical in my opinion.

Personally, I don’t want bells & whistles or a fancy custom website. Something simple that renders docs based on GitHub markdown files (such as GitBook linked above) would be perfect. Developers can submit changes and new examples to the website via Pull Requests. Updates to the code can be paired with corresponding updates to the docs in the same repo. It’s a good ecosystem.

Overall, I’m excited to see official progress in this area and I can’t wait for the final product. I appreciate your continued transparency and earnest requests for feedback. You are all brilliant.

[mav]

@maidsafe

any features which would be important for launch, and features you would like for future iterations.

Not directly about the website but having the site be open source so it can have typos and errata fixed by the community (with maidsafe approval) would be nice. Even simply being able to report issues and feature requests would be handy.

Also a clear plan for removing old resources is important. Otherwise the xkcd standards joke applies.

And versioning the docs pages, like python docs. In theory there’s only ever one api active at a time since the network is global, but for the sake of seo and general information management versioning of docs in sync with versioning of software/apis is really important.

@Shankar_S

@Sascha

please don’t forget about multi-lingual users

Yes, we have plans to integrate internationalization within the dev-website.

Extremely happy for the docs of a global network to be in multiple languages. Please also ensure app developers are reminded to consider i18n for their apps.

---

My personal preference is a strong focus on the APIs and less focus on the tooling (electron, node, rust etc). Examples of api usage in each language is great, but the real emphasis and core website structure should be around the api.

Keep the broader tooling stuff in tutorials. Keep docs focused.

[drehb]

I think MSDN generally does a good job with the way they document each .NET class and provide simple sample code showing how to use the function in each supported language. When I made a SAFE site, I think the main sample code provided by MaidSafe was the email app, and really it was too complex to be of much value to me given that it is in a language & framework that I was unfamiliar with (for me it was more valuable as a user to demo ‘what the network can do’). I used various community members apps that were more simple to study, along with the API playground. So generally what I’d like to see from a SAFEdev website would be MSDN style presentation of the API, with maybe a higher level layer that explains the network, its advantages and how it contrasts with traditional client server apps, and a general overview of how to structure an app (how to use containers vs MDs, etc)

[davidpbrown]

Given SAFE is in Alpha and will be Beta, there needs to be a very clear sense of what is stable and what is volatile. Devs passing by might be more inclined to invest time to something that is clearly stable or gives a clear sense of direction.

https://www.w3schools.com works well… immediately on an unfamiliar topic, it’s declaring a boundary and the limits of the complexity. So, anything along those lines - with examples evidencing the simple mechanics, will encourage those who can get those to work, to try to add some complexity of their own.

Then, we need to not create conflict with other projects but instead draw them towards SAFE. Ideally there would be a pitch directly towards the likes of Ethereum and other ambitious projects about the likelihood of making links between technologies. Any option on that kind of interaction is a force multiplier… little effort for great effect.

So, again most important is some highlight of what is volatile and what is stable and what is evolving. Colour would be my preference for flagging some elements as red - tempting the more ambitious - blue for the evolving - and green for the stable… like ski slopes, allow different level of engagement to see promptly what is at their level. … but jump in immediately with some examples - code; that then engages the reader, rather than challenging them to learn a lot of new terminology before they get a reward… seed many rewards.

Why use the SAFE Network?

Because it removes worry about privacy and security, providing you the freedom to do more.

I see less need to knock the old… people are familiar with what the existing Internet is and their perception of it won’t change for talking it down… talk of what SAFE is - avoid all negatives. Knocking the competition, smacks of insecurity; the Internet has been great but we need to move beyond what we have to something better. Also, don’t be shy about the ambitions that SAFE has. SAFE will provide any environment in which you can apply any programming language you know to build new and exciting applications and with its inbuild revenue system, the sky’s the limit… etc etc.

Pitch that the network is base and a platform on which to build… then provide the tools and pieces by example that allow everyone to play. The more it looks simple the more inclined people will be to try… which again is why code examples are important.

For example… I know nothing of what bootstrap is but I get a sense that I can try it immediately from Bootstrap 3 Tutorial “My First BootStrap Page” right there for me to take.

[Nadia]

Thanks @JPL some great feedback in there, and nice that its crossing over with previous feedback.